cosmiconfig
Advanced tools
Find and load configuration from a package.json property, rc file, or CommonJS module
The cosmiconfig npm package is a utility for finding and loading configuration from a variety of file formats and locations. It is commonly used in Node.js projects to create flexible configuration systems for tools and libraries.
Searching for configuration files
This feature allows you to search for configuration files with a given name in various locations, including package.json properties, rc files, and regular JSON or YAML files.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName');
explorer.search()
.then((result) => {
const config = result ? result.config : {};
// do something with config
})
.catch((error) => {
// handle error
});Loading configuration files directly
This feature allows you to load a configuration file directly from a specified path, regardless of the file's format.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName');
explorer.load('/path/to/config').then((result) => {
const config = result ? result.config : {};
// do something with config
}).catch((error) => {
// handle error
});Creating a custom explorer
This feature allows you to create a custom explorer with specific search places and loaders, enabling you to define where and how configuration files should be found and interpreted.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName', {
searchPlaces: ['custom.config.js', 'package.json'],
loaders: {
'.js': cosmiconfig.loadJs,
'.json': cosmiconfig.loadJson
}
});The 'rc' package is similar to cosmiconfig in that it also searches for and loads configuration files. However, 'rc' focuses on a specific pattern of '.rc' files and does not support as many file formats as cosmiconfig.
The 'config' package is another configuration loader that supports multiple file formats. Unlike cosmiconfig, 'config' is designed for application configuration and has a different approach to file discovery, defaulting to a 'config' directory.
Convict is a configuration management library that includes schema definitions. It is more opinionated than cosmiconfig and includes validation and environment variable support out of the box, which cosmiconfig does not do without additional setup.
Cosmiconfig searches for and loads configuration for your program.
It features smart defaults based on conventional expectations in the JavaScript ecosystem. But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load.
By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:
package.json property.json, .yaml, .yml, or .js..config.js CommonJS moduleFor example, if your module's name is "myapp", cosmiconfig will search up the directory tree for configuration in the following places:
myapp property in package.json.myapprc file in JSON or YAML format.myapprc.json file.myapprc.yaml, .myapprc.yml, or .myapprc.js filemyapp.config.js file exporting a JS objectCosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).
👀 Looking for the v5 docs?
v6 involves slight changes to Cosmiconfig's API, clarifying the difference between synchronous and asynchronous usage.
If you have trouble switching from v5 to v6, please file an issue.
If you are still using v5, those v5 docs are available in the 5.x.x tagged code.
npm install cosmiconfig
Tested in Node 8+.
Create a Cosmiconfig explorer, then either search for or directly load a configuration file.
const { cosmiconfig, cosmiconfigSync } = require('cosmiconfig');
// ...
const explorer = cosmiconfig(moduleName);
// Search for a configuration by walking up directories.
// See documentation for search, below.
explorer.search()
.then((result) => {
// result.config is the parsed configuration object.
// result.filepath is the path to the config file that was found.
// result.isEmpty is true if there was nothing to parse in the config file.
})
.catch((error) => {
// Do something constructive.
});
// Load a configuration directly when you know where it should be.
// The result object is the same as for search.
// See documentation for load, below.
explorer.load(pathToConfig).then(..);
// You can also search and load synchronously.
const explorerSync = cosmiconfigSync(moduleName);
const searchedFor = explorerSync.search();
const loaded = explorerSync.load(pathToConfig);
The result object you get from search or load has the following properties:
undefined if the file is empty.true if the configuration file is empty. This property will not be present if the configuration file is not empty.const { cosmiconfig } = require('cosmiconfig');
const explorer = cosmiconfig(moduleName[, cosmiconfigOptions])
Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.
Type: string. Required.
Your module name. This is used to create the default searchPlaces and packageProp.
If your searchPlaces value will include files, as it does by default (e.g. ${moduleName}rc), your moduleName must consist of characters allowed in filenames. That means you should not copy scoped package names, such as @my-org/my-package, directly into moduleName.
cosmiconfigOptions are documented below.
You may not need them, and should first read about the functions you'll use.
explorer.search([searchFrom]).then(result => {..})
Searches for a configuration file. Returns a Promise that resolves with a result or with null, if no configuration file is found.
You can do the same thing synchronously with explorerSync.search().
Let's say your module name is goldengrahams so you initialized with const explorer = cosmiconfig('goldengrahams');.
Here's how your default search() will work:
process.cwd() (or some other directory defined by the searchFrom argument to search()), look for configuration objects in the following places:
goldengrahams property in a package.json file..goldengrahamsrc file with JSON or YAML syntax..goldengrahamsrc.json file..goldengrahamsrc.yaml, .goldengrahamsrc.yml, or .goldengrahamsrc.js file.goldengrahams.config.js JS file exporting the object../, ../, ../../, ../../../, etc., checking the same places in each directory.stopDir).search() Promise resolves with its result (or, with explorerSync.search(), the result is returned).search() Promise resolves with null (or, with explorerSync.search(), null is returned).search() Promise rejects with that error (so you should .catch() it). (Or, with explorerSync.search(), the error is thrown.)If you know exactly where your configuration file should be, you can use load(), instead.
The search process is highly customizable.
Use the cosmiconfig options searchPlaces and loaders to precisely define where you want to look for configurations and how you want to load them.
Type: string.
Default: process.cwd().
A filename.
search() will start its search here.
If the value is a directory, that's where the search starts. If it's a file, the search starts in that file's directory.
explorer.load(loadPath).then(result => {..})
Loads a configuration file. Returns a Promise that resolves with a result or rejects with an error (if the file does not exist or cannot be loaded).
Use load if you already know where the configuration file is and you just need to load it.
explorer.load('load/this/file.json'); // Tries to load load/this/file.json.
If you load a package.json file, the result will be derived from whatever property is specified as your packageProp.
You can do the same thing synchronously with explorerSync.load().
Clears the cache used in load().
Clears the cache used in search().
Performs both clearLoadCache() and clearSearchCache().
const { cosmiconfigSync } = require('cosmiconfig');
const explorerSync = cosmiconfigSync(moduleName[, cosmiconfigOptions])
Creates a synchronous cosmiconfig instance ("explorerSync") configured according to the arguments, and initializes its caches.
See cosmiconfig().
const result = explorerSync.search([searchFrom]);
Synchronous version of explorer.search().
Returns a result or null.
const result = explorerSync.load(loadPath);
Synchronous version of explorer.load().
Returns a result.
Clears the cache used in load().
Clears the cache used in search().
Performs both clearLoadCache() and clearSearchCache().
Type: Object.
Possible options are documented below.
Type: Array<string>.
Default: See below.
An array of places that search() will check in each directory as it moves up the directory tree.
Each place is relative to the directory being searched, and the places are checked in the specified order.
Default searchPlaces:
[
'package.json',
`.${moduleName}rc`,
`.${moduleName}rc.json`,
`.${moduleName}rc.yaml`,
`.${moduleName}rc.yml`,
`.${moduleName}rc.js`,
`${moduleName}.config.js`,
]
Create your own array to search more, fewer, or altogether different places.
Every item in searchPlaces needs to have a loader in loaders that corresponds to its extension.
(Common extensions are covered by default loaders.)
Read more about loaders below.
package.json is a special value: When it is included in searchPlaces, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file.
That property is defined with the packageProp option, and defaults to your module name.
Examples, with a module named porgy:
// Disallow extensions on rc files:
[
'package.json',
'.porgyrc',
'porgy.config.js'
]
// ESLint searches for configuration in these places:
[
'.eslintrc.js',
'.eslintrc.yaml',
'.eslintrc.yml',
'.eslintrc.json',
'.eslintrc',
'package.json'
]
// Babel looks in fewer places:
[
'package.json',
'.babelrc'
]
// Maybe you want to look for a wide variety of JS flavors:
[
'porgy.config.js',
'porgy.config.mjs',
'porgy.config.ts',
'porgy.config.coffee'
]
// ^^ You will need to designate custom loaders to tell
// Cosmiconfig how to handle these special JS flavors.
// Look within a .config/ subdirectory of every searched directory:
[
'package.json',
'.porgyrc',
'.config/.porgyrc',
'.porgyrc.json',
'.config/.porgyrc.json'
]
Type: Object.
Default: See below.
An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions.
Cosmiconfig exposes its default loaders on a named export defaultLoaders.
Default loaders:
const { defaultLoaders } = require('cosmiconfig');
console.log(Object.entries(defaultLoaders))
// [
// [ '.js', [Function: loadJs] ],
// [ '.json', [Function: loadJson] ],
// [ '.yaml', [Function: loadYaml] ],
// [ '.yml', [Function: loadYaml] ],
// [ 'noExt', [Function: loadYaml] ]
// ]
(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAML or JSON with only one parser.)
If you provide a loaders object, your object will be merged with the defaults.
So you can override one or two without having to override them all.
Keys in loaders are extensions (starting with a period), or noExt to specify the loader for files without extensions, like .myapprc.
Values in loaders are a loader function (described below) whose values are loader functions.
The most common use case for custom loaders value is to load extensionless rc files as strict JSON, instead of JSON or YAML (the default).
To accomplish that, provide the following loaders value:
{
noExt: defaultLoaders['.json']
}
If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from NPM if it exists.
Third-party loaders:
Use cases for custom loader function:
.mjs configuration files.Custom loader functions have the following signature:
// Sync
(filepath: string, content: string) => Object | null
// Async
(filepath: string, content: string) => Object | null | Promise<Object | null>
Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content.
Do whatever you need to, and return either a configuration object or null (or, for async-only loaders, a Promise that resolves with one of those).
null indicates that no real configuration was found and the search should continue.
A few things to note:
cosmiconfigSync()).require hook, because defaultLoaders['.js'] just uses require.
Whether you use custom loaders or a require hook is up to you.Examples:
// Allow JSON5 syntax:
{
'.json': json5Loader
}
// Allow a special configuration syntax of your own creation:
{
'.special': specialLoader
}
// Allow many flavors of JS, using custom loaders:
{
'.mjs': esmLoader,
'.ts': typeScriptLoader,
'.coffee': coffeeScriptLoader
}
// Allow many flavors of JS but rely on require hooks:
{
'.mjs': defaultLoaders['.js'],
'.ts': defaultLoaders['.js'],
'.coffee': defaultLoaders['.js']
}
Type: string | Array<string>.
Default: `${moduleName}`.
Name of the property in package.json to look for.
Use a period-delimited string or an array of strings to describe a path to nested properties.
For example, the value 'configs.myPackage' or ['configs', 'myPackage'] will get you the "myPackage" value in a package.json like this:
{
"configs": {
"myPackage": {..}
}
}
If nested property names within the path include periods, you need to use an array of strings. For example, the value ['configs', 'foo.bar', 'baz'] will get you the "baz" value in a package.json like this:
{
"configs": {
"foo.bar": {
"baz": {..}
}
}
}
If a string includes period but corresponds to a top-level property name, it will not be interpreted as a period-delimited path. For example, the value 'one.two' will get you the "three" value in a package.json like this:
{
"one.two": "three",
"one": {
"two": "four"
}
}
Type: string.
Default: Absolute path to your home directory.
Directory where the search will stop.
Type: boolean.
Default: true.
If false, no caches will be used.
Read more about "Caching" below.
Type: (Result) => Promise<Result> | Result.
A function that transforms the parsed configuration. Receives the result.
If using search() or load() (which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result.
If using cosmiconfigSync, search() or load(), the function must be synchronous and return the transformed result.
The reason you might use this option — instead of simply applying your transform function some other way — is that the transformed result will be cached. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.
Type: boolean.
Default: true.
By default, if search() encounters an empty file (containing nothing but whitespace) in one of the searchPlaces, it will ignore the empty file and move on.
If you'd like to load empty configuration files, instead, set this option to false.
Why might you want to load empty configuration files? If you want to throw an error, or if an empty configuration file means something to your program.
As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with cosmiconfig()) has its own caches.
To avoid or work around caching, you can do the following:
cosmiconfig option cache to false.clearLoadCache(), clearSearchCache(), and clearCaches().rc serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:
package.json property, an rc file, a .config.js file, and rc files with extensions.Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
And please do participate!
6.0.0
Breaking change: The package now has named exports. See examples below.
Breaking change: Separate async and sync APIs, accessible from different named exports. If you used explorer.searchSync() or explorer.loadSync(), you'll now create a sync explorer with cosmiconfigSync(), then use explorerSync.search() and explorerSync.load().
// OLD: cosmiconfig v5
import cosmiconfig from 'cosmiconfig';
const explorer = cosmiconfig('example');
const searchAsyncResult = await explorer.search();
const loadAsyncResult = await explorer.load('./file/to/load');
const searchSyncResult = explorer.searchSync();
const loadSyncResult = explorer.loadSync('./file/to/load');
// NEW: cosmiconfig v6
import { cosmiconfig, cosmiconfigSync } from 'cosmiconfig';
const explorer = cosmiconfig('example');
const searchAsyncResult = await explorer.search();
const loadAsyncResult = await explorer.load('./file/to/load');
const explorerSync = cosmiconfigSync('example');
const searchSyncResult = explorerSync.search();
const loadSyncResult = explorerSync.load('./file/to/load');
Breaking change: Remove support for Node 4 and 6. Requires Node 8+.
Breaking change: Use npm package yaml to parse YAML instead of npm package js-yaml.
Breaking change: Remove cosmiconfig.loaders and add named export defaultLoaders that exports the default loaders used for each extension.
import { defaultLoaders } from 'cosmiconfig';
console.log(Object.entries(defaultLoaders));
// [
// [ '.js', [Function: loadJs] ],
// [ '.json', [Function: loadJson] ],
// [ '.yaml', [Function: loadYaml] ],
// [ '.yml', [Function: loadYaml] ],
// [ 'noExt', [Function: loadYaml] ]
// ]
Migrate from Flowtype to Typescript.
Lazy load all default loaders.
FAQs
Find and load configuration from a package.json property, rc file, TypeScript module, and more!
The npm package cosmiconfig receives a total of 38,360,502 weekly downloads. As such, cosmiconfig popularity was classified as popular.
We found that cosmiconfig demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.